nanospinner

What is nanospinner?

The nanospinner npm package is a lightweight and simple terminal spinner for Node.js applications. It is used to display a spinner in the terminal to indicate that a process is ongoing, which can enhance the user experience by providing visual feedback during long-running operations.

What are nanospinner's main functionalities?

Basic Spinner

This feature allows you to create a basic spinner that starts immediately and stops after a specified duration, indicating success.

const { createSpinner } = require('nanospinner');

const spinner = createSpinner('Loading...').start();

setTimeout(() => {
  spinner.success({ text: 'Done!' });
}, 2000);

Custom Spinner Styles

This feature allows you to customize the spinner style. In this example, the 'dots' style is used, and the spinner indicates failure after a specified duration.

const { createSpinner } = require('nanospinner');

const spinner = createSpinner('Loading...', { spinner: 'dots' }).start();

setTimeout(() => {
  spinner.error({ text: 'Failed!' });
}, 2000);

Spinner with Custom Interval

This feature allows you to set a custom interval for the spinner's animation. The spinner text is updated midway through the process, and it indicates success at the end.

const { createSpinner } = require('nanospinner');

const spinner = createSpinner('Loading...', { interval: 100 }).start();

setTimeout(() => {
  spinner.update({ text: 'Almost there...' });
}, 1000);

setTimeout(() => {
  spinner.success({ text: 'Done!' });
}, 2000);

Other packages similar to nanospinner

ora

Ora is a more feature-rich terminal spinner library for Node.js. It offers a wide range of spinner styles, color customization, and promises support. Compared to nanospinner, Ora provides more customization options and is suitable for more complex use cases.

cli-spinners

Cli-spinners is a collection of various spinner animations for use in the terminal. It is often used in conjunction with other libraries like Ora to provide a wide range of spinner styles. While cli-spinners itself does not manage the spinner state, it offers a large selection of animations that can be used with other spinner libraries.

listr

Listr is a library for creating elegant CLI task lists with progress spinners. It is designed for managing multiple tasks with nested subtasks and provides a more structured approach to displaying progress in the terminal. Compared to nanospinner, Listr is more suitable for complex task management scenarios.

README

Nano Spinner

The simplest and tiniest terminal spinner for Node.js

import { createSpinner } from 'nanospinner'

const spinner = createSpinner('Run test').start()

setTimeout(() => {
  spinner.success()
}, 1000)

• Only single dependency (picocolors).
• It 45 times smaller than ora.
• Support both CJS and ESM projects.
• TypeScript type declarations included.

Motivation

With nanospinner we are trying to draw attention to the node_modules size problem and promote performance-first culture.

Benchmarks

The space in node_modules including sub-dependencies:

$ node ./test/size.js
Data from packagephobia.com
  ora           597 kB
+ nanospinner    13 kB

API

.spin()

Looping over spin method will animate a given spinner.

setInterval(() => {
  spinner.spin()
}, 25)

.start(options?)

In order to start the spinner call start. This will perform drawing the spinning animation

spinner.start()
spinner.start({ text: 'Start', color: 'yellow' })

.stop(options?)

In order to stop the spinner call stop. This will finish drawing the spinning animation and return to new line.

spinner.stop()
spinner.stop({ text: 'Done!', mark: ':O', color: 'magenta' })

.success(options?)

Use success call to stop the spinning animation and replace the spinning symbol with check mark character to indicate successful completion.

spinner.success()
spinner.success({ text: 'Successful!', mark: ':)' })

.warn(options?)

Use warn call to stop the spinning animation and replace the spinning symbol with warn mark character to indicate warning completion.

spinner.warn()
spinner.warn({ text: 'Warning!', mark: ':|' })

.error(options?)

Use error call to stop the spinning animation and replace the spinning symbol with cross character to indicate error completion.

spinner.error()
spinner.error({ text: 'Error!', mark: ':(' })

.update(options?)

Use update call to dynamically change

spinner.update({
  text: 'Run test',
  color: 'white',
  stream: process.stdout,
  frames: ['.', 'o', '0', '@', '*'],
  interval: 100,
})

.clear()

Clears the spinner`s output

spinner.clear()

.reset()

In order to reset the spinner to its initial frame do:

spinner.reset()

Roadmap

• Multi spinners